Notes/Domino 6 and 7 Forum : Using Java Cryptography Extension (JCE) with ND6

I had a learning curve while trying to get this setup, and seen similar comments from others. So, I figured I'd post my success with this in hopes it will provide some help to those dealing with this.

Things to do (and avoid doing) while settting up IBM Java Cryptography Extension (JCE) under Domino R6
** This document was written in regards to Domino 6.0.2. You may be able to apply some, if not all, of the steps below to other JCE providers.

Background notes:
1. ND6 ships with JVM version IBM 1.3.1. { Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1) Classic VM (build 1.3.1, J2RE 1.3.1 IBM Windows 32 ) }
2. ND6 ships with a jar file in the directory {java_home}\lib\ext named ibmjcaprovider.jar. ( ex., {java_home} as "C:\Program Files\notes6\jvm" ). This is the IBMJCA version of the encryption package. IBMJCE is an entirely different and more complete set of encryption classes.
3. Make sure you have the latest IBM JCE code (or whatever JCE you're using). JCE is only available to work under Java version 1.2 or greater (Java 2). Hence, this will not work under Domino R5 unless the JVM is updated ( R5 uses JVM version 1.1.8).
4. While using the Cipher class, use the overloaded method 'getInstance' with two parameters, with the provider name as the second. This ensures the correct provider is used to generate the Cipher class. Example: Cipher ciph = Cipher.getInstance( "PBEWithSHAAnd128bitRC4", "IBMJCE" );

How to install:
1. Place the JCE jars in the {java_home}\lib\ext directory. There are 6 jars in version 1.2.1: ibmjceprovider.jar, ibmjcefw.jar, ibmpkcs.jar, ibmpkcs11.jar, local_policy.jar, US_export_policy.jar. Rename the existing ibmjcaprovider.jar file to something else.
2. Replace the IBMJCA provider with the IBMJCE provider or comment the line from the file java.policy (also named java.pol or similar) in the \lib\security subdirectory. You may also add a provider dynamically within your java code, using the Security.addProvider or Security.insertProviderAt methods.

example (original):
# List of providers and their preference orders:
security.provider.1=sun.security.provider.Sun
security.provider.2=com.ibm.crypto.provider.IBMJCA

example (updated):
# List of providers and their preference orders:
security.provider.1=sun.security.provider.Sun
security.provider.2=com.ibm.crypto.provider.IBMJCE

It is important to note that both the IBMJCA provider and the IBMJCE provider CANNOT both be present, as this will cause conflicts. Choose one or the other, but not both. Also, the Sun provider must be listed as the default provider (1), and the IBMJCE provider is next (2).

3. Make sure your java agent or java library references the IBMJCE jars as appropriate just like any other java program. In my experience, putting jars in the \lib\ext directory allows the JVM running under Domino to find the jar files, WITHOUT having to make references to the jar files in notes.ini file under the pararmeter JavaUserClasses=. It also allows you to compile java agents and libraries without adding the jars explicitly to your project. If your setup differs, you may need alter one or both of these items.

Randy Simms
rsimms@us.ibm.com